Summary

• Update the OpenAI Python integration page and the structured output cookbook to recommend client.chat.completions.parse(...) for openai>=1.92.0 and scope the beta caveat to older SDK versions.
• Note that the Langfuse Python SDK instruments both the stable (openai.resources.chat.completions.Completions.parse) and the legacy beta path, so Langfuse attributes (name, metadata, langfuse_session_id, …) work on either.
• Keep the response_format + type_to_response_format_param example as a fallback for users who cannot upgrade openai.

Why

Reported by David Traina (Ramp) in Pylon #1339. OpenAI moved parse/stream out of beta in openai-python v1.92.0 ~10 months ago, but our docs still warned against the beta API and pushed users to response_format + chat.completions.create. The SDK has already supported the stable path for a while — only the docs were stale.

Test plan

• pnpm dev and verify the Structured Output section on /integrations/model-providers/openai-py renders correctly.
• Verify the regenerated /guides/cookbook/integration_openai_structured_output page renders the updated note and parse example.

🤖 Generated with Claude Code

Disclaimer: Experimental PR review

Greptile Summary

This PR corrects stale documentation that incorrectly told users to avoid client.chat.completions.parse in favour of response_format + create. It updates both the integration page and the cookbook to recommend the stable parse API (available since openai-python v1.92.0) and preserves a type_to_response_format_param fallback for users who cannot upgrade.

Confidence Score: 4/5

Safe to merge — documentation-only changes with accurate technical content and only minor style observations.

All three files are docs/notebook updates with no runtime code. The guidance is factually correct. The only findings are P2: a private-API import risk in the legacy fallback (pre-existing pattern, not introduced here) and mildly ambiguous phrasing in one note.

No files require special attention; the private import in openai-py.mdx is worth a comment but is not blocking.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User wants Structured Output\nwith Langfuse tracing] --> B{openai SDK version?}
    B -- ">=1.92.0\n(recommended)" --> C["client.chat.completions.parse(...)\nresponse_format=PydanticModel\nname='...' metadata={...}"]
    B -- "<1.92.0\n(legacy)" --> D{Pydantic model needed?}
    D -- Yes --> E["client.beta.chat.completions.parse(...)\nresponse_format=PydanticModel\n(re-routed to stable on >=1.92.0)"]
    D -- No / can't upgrade --> F["type_to_response_format_param(Model)\n→ client.chat.completions.create(...)\nresponse_format=schema_dict"]
    C --> G[Langfuse traces both name\nand metadata attributes ✓]
    E --> G
    F --> G

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
content/integrations/model-providers/openai-py.mdx:101
**Private internal API in legacy fallback**

`openai.lib._parsing._completions` is an underscore-prefixed internal module — it is not part of OpenAI's public API surface and can be removed or renamed without a semver-breaking release. Users who follow this fallback path are silently depending on an implementation detail that could break on any minor OpenAI SDK bump, even within `<1.92.0`. Consider noting this risk explicitly, or suggesting users pin their OpenAI version when using this path.

### Issue 2 of 2
content/guides/cookbook/integration_openai_structured_output.md:58
**Slightly ambiguous parenthetical in the note**

The clause "for older SDK versions, where `parse` is re-routed to the stable method on newer SDKs" embeds a forward-reference to newer-SDK behaviour inside the description of the older-SDK path, which can read as contradictory. Consider splitting the two facts into separate sentences, e.g. "…the legacy `client.beta.chat.completions.parse(...)` (available on `openai<1.92.0`). On `openai>=1.92.0` the OpenAI SDK re-routes beta calls to the stable method, so either path reaches the same instrumented function."

_{Reviews (1): Last reviewed commit: "docs: clarify OpenAI Python parse vs res..." | Re-trigger Greptile}